SOF-8025: lead with the ontology, and with "AI for Materials" as the wordmark - #427
Merged
Conversation
Two changes that travel together, since both are about what a first-time visitor understands the site to be. The corpus is an ontology and never said so. It fixes what kinds of thing exist in digital materials science and how they relate, and the relations are declared rather than editorial: `extends` is subsumption (is a), `contains` is composition (has a), `variant` is disjunction (is one of), with controlled vocabularies constraining the leaves. The word appeared nowhere in the docs or on the map. It does now: - The map's empty detail panel leads with "The ontology, mapped" and explains that nodes are entity types and edges are declared relationships -- the panel is the first thing a visitor reads, so it does the defining. - `01-why-esse-exists` gains a section stating the claim and, importantly, its limit: this is not OWL/RDF with a reasoner, and the trade is deliberate -- expressed as JSON Schema, the ontology validates records directly instead of describing a world some other artifact must conform to. - A new `ontology-relations` generated fragment tabulates the three relations against their JSON Schema keywords with counts from the graph, so the prose calling them "the familiar ontological relations" cannot drift. - Glossary gains Ontology and Data standard under "The corpus". The wordmark becomes "AI for Materials" across all three surfaces, with "ESSE - data standards & ontology" as the descriptor. Worth recording that this was chosen over keeping ESSE primary: it maximises reach to the AI-for-materials audience, at the cost of immediate recognition for someone arriving from `npm i @mat3ra/esse`, which the descriptor is there to recover. The docs now carry an honest account of the AI connection -- declared types, units and relationships are what training pipelines and agents would otherwise have to infer -- rather than leaving the framing unsupported. The docs titlebar had no tagline slot at all; it gains one, hidden under 640px. Verified in a browser that the longer wordmark neither spills, overlaps its neighbours nor introduces horizontal scroll on any of the three surfaces at 1440/999/760/560px, with the map still rendering 564 nodes and no console errors. 34 tests pass, all internal links resolve.
The nav now reads Docs / Explorer / Ontology: three views of one thing, and the label finally names what the surface shows rather than how it is drawn. Page title, README, and the ~16 prose references follow, with "the ontology map" as the lowercase descriptive form when the sentence is about looking at it rather than about the artifact. The URL stays `/map/`, deliberately. `#/entity/<$id>` deep links were recorded as a stability contract, the path is already live and linked from outside the repository, and 26 internal references point at it. Labels are what people read; paths are plumbing, and this one is load-bearing. Verified in a browser on all three surfaces at 1440/760/560px: the nav reads correctly, the right item is marked current on each surface, and nothing spills, overlaps or introduces horizontal scroll. 34 tests pass and all internal links resolve.
"AI for Materials" alone read as a dangling fragment -- the name sat at the far left of the titlebar while its descriptor was stranded on the other side of the navigation, so the logo never resolved into a phrase. The name and its completion are now one unit. The suffix is muted and lighter so the name still carries the emphasis, and it drops below 700px where the navigation needs the room. The right-hand slot keeps `ESSE - materials science ontology`, which is where package-name recognition now lives. Closed-up with the numeral rather than "AI for Materials": AI4Science and ML4Sci have made that the idiom in this field, so it reads as a name rather than as textspeak. Verified in a browser on all three surfaces at 1440/900/700/560px: the logo renders in full, the suffix hides exactly at the 700px breakpoint, and nothing spills, overlaps or introduces horizontal scroll. 34 tests pass, all internal links resolve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes that travel together, since both are about what a first-time visitor understands the site to be.
The corpus is an ontology and never said so
The word appeared nowhere in the docs or on the map. It should, because the claim is well-founded and mechanically checkable: ESSE fixes what kinds of thing exist in digital materials science and how they relate, and the relations are declared rather than editorial.
extendsallOfcontainsproperties/itemsvariantoneOf/anyOfChanges:
<title>/description follow.01-why-esse-existsgains a section stating the claim and its limit: this is not OWL/RDF with a description-logic reasoner, and the trade is deliberate — expressed as JSON Schema, the ontology validates records directly rather than describing a world some other artifact must then conform to.ontology-relationsgenerated fragment renders the table above from the graph, so prose calling these "the familiar ontological relations" cannot drift from what the corpus declares.OntologyandData standardunder "The corpus".Wordmark
AI for Materialsacross all three surfaces, withESSE · data standards & ontologyas the descriptor.Recording the trade-off, since it was a deliberate choice over keeping ESSE primary: this maximises reach to the AI-for-materials audience, at the cost of immediate recognition for someone arriving from
npm i @mat3ra/esse— which the descriptor is there to recover. The docs now also carry an honest account of why the AI framing fits (declared types, units and relationships are exactly what a training pipeline or an agent would otherwise have to infer from examples), rather than leaving the claim unsupported by the content.The docs titlebar had no tagline slot at all; it gains one, hidden under 640px.
Verification
AI for Materialsis substantially wider thanESSE, so the titlebar layout was the real risk. Checked in a real browser on all three surfaces at 1440 / 999 / 760 / 560px, asserting programmatically that nothing spills past the titlebar, no two elements overlap, and no horizontal scroll appears — clean in all 12 combinations. The map still renders 564 nodes with zero console errors, and the docs tagline correctly hides at 560px.Also fixed while there: the map's empty panel ran its "what this is" and "how to drive it" paragraphs together with no separation — the hint line now has a rule above it.
34 JS tests pass; all internal links resolve; eslint and prettier clean.
🤖 Generated with Claude Code
Generated by Claude Code